package uk.ac.ebi.uniprot.wikipedia.retrievalServices;

import uk.ac.ebi.kraken.interfaces.uniprot.UniProtEntry;
import uk.ac.ebi.uniprot.wikipedia.exceptions.NoSuchOrganismException;
import uk.ac.ebi.uniprot.wikipedia.exceptions.RetrievalException;
import uk.ac.ebi.uniprot.wikipedia.exceptions.ServiceException;
import uk.ac.ebi.uniprot.wikipedia.exceptions.UnexpectedException;
import uk.ac.ebi.uniprot.wikipedia.util.GeneWikiOrganism;

import java.util.List;

/**
 * Created with IntelliJ IDEA.
 * User: ljgarcia
 * Date: 29/06/12
 * Time: 10:42
 * To change this template use File | Settings | File Templates.
 */
public interface UniProtRetrieval {
    /**
     * Bean initialization.
     * @throws ServiceException
     */
    public void init() throws ServiceException;

    /**
     * Retrieves a UniProt entry whose accession or identifier matches to the given one; the organism
     * should mathc as well.
     * @param accessionOrId Accession or identifier to look for.
     * @param organism Organism to look for.
     * @return UniProt entry.
     * @throws ServiceException Whenever there is a problem related to the beans.
     * @throws NoSuchOrganismException Whenever the organism in the retrieved entry does not match.
     */
    public UniProtEntry getEntryByAccessionAndOrganism(String accessionOrId, GeneWikiOrganism organism) throws UnexpectedException, NoSuchOrganismException, RetrievalException, ServiceException;

    /**
     * Retrieves all UniProt entries whit a cross reference to the given gene id; the organism
     * should mathc as well.
     * @param geneId Gene id to look for.
     * @param organism Organism to look for.
     * @param onlyReviewed Should the entries necessarily be reviewed?
     * @return UniProt entry.
     * @throws ServiceException Whenever there is a problem related to the beans.
     */
    public List<UniProtEntry> getEntryByGeneIdAndOrganism(String geneId, GeneWikiOrganism organism, boolean onlyReviewed) throws ServiceException;

    /**
     * Destroys the bean.
     */
    public void destroy();
}
